GLOBAL(1)                   General Commands Manual                  GLOBAL(1)



[1mNAME[0m
       global - print locations of given symbols

[1mSYNOPSIS[0m
       [1mglobal [22m[-adEFGilMnNqrstTvx][-S dir][-e] [4mpattern[0m
       [1mglobal [22m-c[dFiIMoOPrsT] [4mprefix[0m
       [1mglobal [22m-f[adlnqrstvx][-L file-list][-S dir] [4mfiles[0m
       [1mglobal [22m-g[aEGilMnoOqtvVx][-L file-list][-S dir][-e] [4mpattern[24m [[4mfiles[24m]
       [1mglobal [22m-I[ailMnqtvx][-S dir][-e] [4mpattern[0m
       [1mglobal [22m-P[aEGilMnoOqtvVx][-S dir][-e] [4mpattern[0m
       [1mglobal [22m-p[qrv]
       [1mglobal [22m-u[qv]

[1mDESCRIPTION[0m
       [1mGlobal  [22mfinds  locations of given symbols in C, Yacc, Java, PHP and as-
       sembly source files, and prints the path name, line number and line im-
       age  of the locations.  [1mGlobal [22mcan locate not only definitions but also
       references and other symbols.

       [1mGlobal [22mcan treat a source tree, that is, a directory that  has  sub-di-
       rectories  and  source  files,  as a project.  In advance of using this
       command, you must execute [1mgtags[22m(1) at the root directory of the project
       which  you  want  to  investigate  to make tag files.  Then you can use
       [1mglobal [22mcommand anywhere in the project.  You need not specify where the
       tag file is.  Instead, [1mglobal [22mlocates it by itself.

       You  can  specify a regular expression for [4mpattern[24m.  [1mGlobal [22munderstands
       two different versions of regular expression syntax: basic and extended
       (default).

[1mCOMMANDS[0m
       The following commands are available:

       <no command> [4mpattern[0m
              No  command means tag search command.  Print tags which match to
              [4mpattern[24m.  By default, print definition tags.

       [1m-c[22m, [1m--completion [22m[[4mprefix[24m]
              Print symbols which start with [4mprefix[24m.  If [4mprefix[24m is not  given,
              print all symbols.

       [1m-f[22m, [1m--file [4m[22mfiles[0m
              Print  all  tags  in the [4mfiles[24m.  This command implies the [1m-x [22mop-
              tion.

       [1m-g[22m, [1m--grep [4m[22mpattern[24m [[4mfiles[24m]
              Print all lines which match to the [4mpattern[24m.  If [4mfiles[24m are given,
              this command searches in those files.

       [1m--help [22mPrint a usage message.

       [1m-I[22m, [1m--idutils [4m[22mpattern[0m
              Print all lines which match to [4mpattern[24m.  This function uses [1midu-[0m
              [1mtils[22m(1) as a search engine.  To use this command,  you  need  to
              install  [1midutils[22m(1) in your system and execute [1mgtags[22m(1) with the
              [1m-I [22moption.

       [1m-P[22m, [1m--path [22m[[4mpattern[24m]
              Print path names which match  to  [4mpattern[24m.   If  no  pattern  is
              given, print all paths in the project.

       [1m-p[22m, [1m--print-dbpath[0m
              Print location of 'GTAGS'.

       [1m--print [4m[22mname[0m
              Print location of [4mname[24m, which may be one of: 'root', 'dbpath' or
              'conf'.  'root' means project's root directory. 'dbpath' means a
              directory  where tag databases exist. 'conf' means configuration
              file.

       [1m-u[22m, [1m--update[0m
              Update tag files incrementally.  This command internally invokes
              [1mgtags[22m(1).  You can execute this command anywhere in the project,
              differing from [1mgtags[22m(1).

       [1m--version[0m
              Show version number.

[1mOPTIONS[0m
       The following options are available:

       [1m-a[22m, [1m--absolute[0m
              Print absolute path  names.  By  default,  print  relative  path
              names.

       [1m--color [4m[22mwhen[0m
              Use  color to highlight the pattern within the line; [4mwhen[24m may be
              one of: [4mnever[24m, [4malways[24m or [4mauto[24m (default).  The default  color  is
              bold  red  text  on current background; the environment variable
              [1mGREP_COLORS [22m(only  [1mmt  [22mand  [1mms  [22mare  effective  at  present)  or
              [1mGREP_COLOR  [22mdefines it.  This option is effective to the follow-
              ing commands: <no command>, -f, -g, -I, -P.

       [1m-C[22m, [1m--directory [4m[22mdir[0m
              Change the directory before doing all the work including parame-
              ter analysis.

       [1m-d[22m, [1m--definition[0m
              Print locations of definitions.

       [1m-e[22m, [1m--regexp [4m[22mpattern[0m
              Use  [4mpattern[24m as the pattern; useful to protect patterns starting
              with '-'.

       [1m-E[22m, [1m--extended-regexp[0m
              Interpret [4mpattern[24m as a extended regular expression.  This is the
              default.

       [1m--encode-path [4m[22mchars[0m
              Convert  path characters in [4mchars[24m into a '%' symbol, followed by
              the two-digit hexadecimal representation of  the  character.   A
              blank will be converted to '%20'.

       [1m-F[22m, [1m--first-match[0m
              End the search without going through all the tag files listed in
              [1mGTAGSLIBPATH [22mwhen tags are found in a tag file. This is the  de-
              fault.

       [1m--from-here [4m[22mcontext[0m
              Decide  tag type by [4mcontext[24m. Its syntax should be 'lineno:path'.
              If the context is a definition of the pattern then use [1m-r[22m,  else
              if  there is at least one definition of the pattern then use [1m-d[22m,
              else use [1m-s[22m.  If this option is specified then [1m-d[22m, [1m-r [22mand [1m-s  [22mon
              the command line are ignored.  Regular expression is not allowed
              for [4mpattern[24m.  This option assumes use in conversational environ-
              ments such as editors and IDEs.

       [1m-G[22m, [1m--basic-regexp[0m
              Interpret [4mpattern[24m as a basic regular expression.  The default is
              an extended regular expression.

       [1m--gtagsconf [4m[22mfile[0m
              Set environment variable [1mGTAGSCONF [22mto [4mfile[24m.

       [1m--gtagslabel [4m[22mlabel[0m
              Set environment variable [1mGTAGSLABEL [22mto [4mlabel[24m.

       [1m-i[22m, [1m--ignore-case[0m
              Ignore case distinctions in the pattern.

       [1m-L[22m, [1m--file-list [4m[22mfile[0m
              Obtain files from [4mfile[24m in addition to the arguments.  The  argu-
              ment  [4mfile[24m  can be set to '-' to accept a list of files from the
              standard input. File names must be separated by newline.

       [1m-l[22m, [1m--local[0m
              Print only tags which exist under the current directory.

       [1m--literal[0m
              Execute literal search instead  of  regular  expression  search.
              This  option  works  with the tag search command, [1m-g [22mcommand, [1m-P[0m
              command and [1m-I [22mcommand.

       [1m-M[22m, [1m--match-case[0m
              Search is case-sensitive. This is the default.

       [1m--match-part [4m[22mpart[0m
              Specify how path name completion should match, where [4mpart[24m is one
              of:  'first',  'last'  or 'all' (default).  This option is valid
              only with the [1m-c [22mcommand in conjunction with [1m-P[22m.

       [1m-n[22m, [1m--nofilter[0m
              Suppress sort filter and path conversion filter.

       [1m-N[22m, [1m--nearness[22m[=[4mstart[24m]
              Use Nearness sort method (sorting by closest from [4mstart[24m) for the
              output.  By default, alphabetical sort method is used.  This op-
              tion is effective for the tag search command, [1m-P [22mcommand and  [1m-g[0m
              command.  As  an  exception, [1m-g [22mcommand ignores this option when
              files are specified by arguments.  The nearness  is  defined  by
              how  many  parent  directories to go up to reach the target. The
              result of  nearness  sort  is  concatenation  of  the  following
              ([0]-[n]) in this order. The default of [4mstart[24m is the current di-
              rectory.
              [0] If the start is a file, output of local search in the file.
              [1] Output of local search in the start directory except for [0].
              [2] Output of local search in the parent directory except for [0]-[1].
              [3] Output of local search in the grandparent directory except for [0]-[2].
              ... (repeat until the project root directory)
              [n] Output of local search in the project root directory except for [0]-[n-1].
              In each directory, they are sorted by alphabetical order.

       [1m-O[22m, [1m--only-other[0m
              Treat only text files other than  source  code,  like  'README'.
              This  option  is valid only with the [1m-g [22mor [1m-P [22mcommand.  This op-
              tion overrides the [1m-o [22moption.

       [1m-o[22m, [1m--other[0m
              Treat not only source files  but  also  text  files  other  than
              source  code, like 'README'.  This option is valid only with the
              [1m-g [22mor [1m-P [22mcommand.

       [1m--path-style [4m[22mformat[0m
              Print path names using [4mformat[24m, which may be one of:  'relative',
              'absolute',  'shorter', 'abslib' or 'through'.  'relative' means
              relative path. 'absolute' means absolute path.  'shorter'  means
              the  shorter  one of relative and absolute path.  'abslib' means
              absolute path for libraries (GTAGSLIBPATH) and relative path for
              the  rest.   'through'  means the relative path from the project
              root directory (internal format of GPATH).  The default is 'rel-
              ative'.  The [1m--path-style [22moption is given more priority than the
              [1m-a [22moption.

       [1m--print0[0m
              Print each record followed by a null character instead of a new-
              line.

       [1m-q[22m, [1m--quiet[0m
              Quiet mode.

       [1m-r[22m, [1m--reference[22m, [1m--rootdir[0m
              Print reference tags.  Reference means the reference to a symbol
              which has definitions.  With the [1m-p [22moption, print the  root  di-
              rectory of the project.

       [1m--result [4m[22mformat[0m
              Print  out  using [4mformat[24m, which may be one of: 'path' (default),
              'ctags', 'ctags-x', 'grep' or 'cscope'.  The [1m--result=ctags  [22mand
              [1m--result=ctags-x [22moptions are equivalent to the [1m-t [22mand [1m-x [22moptions
              respectively.  The [1m--result [22moption is given more  priority  than
              the [1m-t [22mand [1m-x [22moptions.

       [1m--single-update [4m[22mfile[0m
              Update tag files using [1mgtags[22m(1) with the [1m--single-update [22moption.
              It is considered that [4mfile[24m was added, updated  or  deleted,  and
              there  is  no change in other files.  This option implies the [1m-u[0m
              option.

       [1m-s[22m, [1m--symbol[0m
              Print other symbol tags.  Other symbol means the reference to  a
              symbol which has no definition.

       [1m-S[22m, [1m--scope [4m[22mdir[0m
              Print  only tags which exist under [4mdir[24m directory.  It is similar
              to the [1m-l [22moption, but you need not change directory.

       [1m-T[22m, [1m--through[0m
              Go through all the tag files listed  in  [1mGTAGSLIBPATH[22m.   By  de-
              fault, stop searching when tag is found.  This option is ignored
              when either [1m-s[22m, [1m-r [22mor [1m-l [22moption is specified.

       [1m-t[22m, [1m--tags[0m
              Use standard ctags format.

       [1m-V[22m, [1m--invert-match[0m
              Invert the sense of  matching,  to  select  non-matching  lines.
              This option is valid only with the [1m-g [22mor [1m-P [22mcommands.

       [1m-v[22m, [1m--verbose[0m
              Verbose mode.

       [1m-x[22m, [1m--cxref[0m
              Use standard ctags cxref (with [1m-x[22m) format.

[1mEXAMPLES[0m
       $ ls -F
       Makefile      src/    lib/
       $ gtags
       $ ls G*
       GPATH   GRTAGS  GTAGS
       $ global main
       src/main.c
       $ (cd src; global main)
       main.c
       $ global -x main
       main              10 src/main.c  main (argc, argv) {
       $ global -f src/main.c
       main              10 src/main.c  main (argc, argv) {
       func1             55 src/main.c  func1() {
       func2             72 src/main.c  func2() {
       func3            120 src/main.c  func3() {
       $ global -x '^[sg]et'
       set_num           20 lib/util.c  set_num(values) {
       get_num           30 lib/util.c  get_num() {
       $ global -rx set_num
       set_num          113 src/op.c            set_num(32);
       set_num          225 src/opop.c               if (set_num(0) > 0) {
       $ global strlen
       $ (cd /usr/src/sys; gtags)
       $ export GTAGSLIBPATH=/usr/src/sys
       $ global -a strlen
       /usr/src/sys/libkern/strlen.c
       $ (cd /usr/src/lib; gtags)
       $ GTAGSLIBPATH=/usr/src/lib:/usr/src/sys
       $ global -a strlen
       /usr/src/lib/libc/string/strlen.c

[1mFILES[0m
       'GTAGS'
              Tag file for definitions.

       'GRTAGS'
              Tag file for references.

       'GPATH'
              Tag file for source files.

       'GTAGSROOT'
              If  environment  variable  [1mGTAGSROOT [22mis not set and file 'GTAGS-
              ROOT' exists in the same directory as 'GTAGS' then  [1mglobal  [22msets
              [1mGTAGSROOT [22mto the contents of the file.

       'gtags.conf', '$HOME/.globalrc'
              Configuration data for GNU Global.  See [1mgtags.conf[22m(5).

[1mENVIRONMENT[0m
       The following environment variables affect the execution of [1mglobal[22m:

       [1mGREP_COLOR[0m
              The color to use for [1m--color[22m; [1mGREP_COLORS [22mhas precedence.

       [1mGREP_COLORS[0m
              The color ([4mmt[24m or [4mms[24m) to use for [1m--color[22m; see [1mgrep[22m(1).

       [1mGTAGSBLANKENCODE[0m
              If  this  variable  is set, the [1m--encode-path=" <TAB>" [22moption is
              specified.

       [1mGTAGSCACHE[0m
              The size of the B-tree cache. The default is 50000000 (bytes).

       [1mGTAGSCONF[0m
              Configuration file.

       [1mGTAGSDBPATH[0m
              The directory in which the tag files exist.  This value  is  ig-
              nored  when  [1mGTAGSROOT  [22mis not defined.  Use of this variable is
              not recommended.

       [1mGTAGSFORCECPP[0m
              If this variable is set, each  file  whose  suffix  is  '.h'  is
              treated as a C++ source file.

       [1mGTAGSLABEL[0m
              Configuration label. The default is [4mdefault[24m.

       [1mGTAGSLIBPATH[0m
              If  this  variable  is set, it is used as the path to search for
              library functions. If the given symbol is not found in the  cur-
              rent  project,  [1mglobal [22malso searches in these paths.  Since only
              'GTAGS' is targeted in the retrieval, this variable  is  ignored
              when [1m-r [22mor [1m-s [22mis specified.

       [1mGTAGSLOGGING[0m
              If  this  variable  is  set, '$GTAGSLOGGING' is used as the path
              name of a log file. There is no default value.

       [1mGTAGSROOT[0m
              The root directory of the project.  Usually, it is recognized by
              existence of 'GTAGS'.  Use of this variable is not recommended.

       [1mGTAGSTHROUGH[0m
              If this variable is set, the [1m-T [22moption is specified.

       [1mGTAGSOBJDIR[22m, [1mMAKEOBJDIR[0m
              If  eigher of the two variable is set, it is used as the name of
              BSD-style objdir.  The former is given priority. The default  is
              'obj'.

       [1mGTAGSOBJDIRPREFIX[22m, [1mMAKEOBJDIRPREFIX[0m
              If  eigher  of the two variable is set, it is used as the prefix
              of BSD-style objdir.  The former is given priority. The  default
              is '/usr/obj'.

[1mCONFIGURATION[0m
       The following configuration variables affect the execution of [1mglobal[22m:

       icase_path (boolean)
              Ignore case distinctions in [4mpattern[24m.

[1mDIAGNOSTICS[0m
       [1mGlobal [22mexits with a non-0 value if an error occurred, 0 otherwise.

[1mSEE ALSO[0m
       [1mgtags[22m(1), [1mhtags[22m(1), [1mless[22m(1), [1mgtags.conf[22m(5).

       GNU Global source code tag system
       (http://www.gnu.org/software/global/).

[1mAUTHOR[0m
       Shigio YAMAGUCHI, Hideki IWAMOTO and others.

[1mHISTORY[0m
       The [1mglobal [22mcommand appeared in FreeBSD 2.2.2.



GNU Project                        May 2015                          GLOBAL(1)
